Authentication APIs Overview
Pyramid's APIs for authentication are designed to facilitate numerous techniques for authenticating and authorizing user access to Pyramid programmatically.
The APIs used for authentication can be found here.
Authentication Flows
The following explains the general approaches, which can be split into 3 basic flows:
- Client Login: automation of user logins into the main product
- API Login: automation of (admin) user logins to access REST API methods
- Embed Login: automation of user logins into content hosted on a 3rd party site using embedding
Flows 1 and 2 are identical in essence - with only variations in how the authorization tokens are used. While flow 3 is not significantly different from the other flows.
Client Login
To log a user into Pyramid, the calling code needs to supply the user's username and password (the same used for manual login). The code then calls one of the authentication methods through a REST call. If the call succeeds, the response is a string of characters called the "token". This token needs to be saved in the browser session as a special cookie. When browsing to the main client, the login step is skipped once this cookie is recognized and validated - effectively providing a programmatic entry into the main application.
Client Login by Admin Token
There are situations where programmatic login to the main application can not involve the end user's password (because it is unknown). Authenticating by "token" is provided as a solution in a 2 phase API process:
- First an administrative account performs the standard login process described above
- Then the admin token -generated in phase 1 - is used to authenticate the user (with their username only) instead. The second token generated is then saved to the browser cookie to provide the end-user with programmatic access.
API Login
NOTE: All REST API calls are limited to administrative users only.
API login is identical to the client login flow above. To log an administrative user into Pyramid for API access, the calling code needs to supply the admin's username and password (the same used for manual login). The code then calls one of the authentication methods through a REST call. If the call succeeds, the response is a string of characters called the "token". This token needs to be stored in the calling code and appended to the JSON request payload for each and every API method call from the calling code.
Embed Login
Embed logins follow a similar pattern. The calling code needs to supply the username and password to the embed authentication API. The resulting string needs to be saved as a special cookie into the browser, which in turn will allow embedded content in the browser to work. The only difference between embed tokens and client tokens is that embed tokens are designed to operate in web domains that are NOT the same as the Pyramid web domain itself (a typical requirement in embedding scenarios).
Embed Login by Admin Token
Like client token authentication, embed token authentication allows the calling code to authorize a user's access to Pyramid through the usage of an admin token instead of the end user's password.
Windows Authentication Logins
A special set of authentication API's exist for customers using Windows Authentication. This allows the credentials of the currently logged-in user to be used. This is a convenient method for SSO login to Pyramid itself. This capability applies to client, API and embed flows alike.
Technologies
The Authentication APIs are executed via REST calls and can be initiated from any technology that can send and receive REST methods. This includes JavaScript, Java, C# and Python.
However, since most authentication procedures should happen securely, Pyramid strongly recommends that all calls be primarily handled via compiled software solutions to ensure no credentials are discoverable. This is especially true for authentication by token, where the administrative account details need to be secured well.